Integration Best Practices for Cloudinary Technology Partners

Before you get started on any development work, we recommend you sign up for a free Cloudinary demo account to get familiar with the Cloudinary offering. Once your account is set up, you can also access our free training site, Cloudinary Academy as well as our Knowledgebase and Documentation sites.

Ready to go? Great! Request an initial discovery call by sending an email to integrations@cloudinary.com. After signing a tech partner agreement, the Cloudinary team can upgrade your Cloudinary account to help you get better visibility with our support team.

Become Familiar With Cloudinary Product Offerings

Take time to understand Cloudinary’s products, the value they bring to users, and how they can be incorporated into Cloudinary integrations.

The integration you build should enable only features that are available for the products your customer is using.

Programmable Media

Customers who use Cloudinary’s Programmable Media offering benefit from the full feature set of Cloudinary. This includes access to all of Cloudinary’s APIs, transformations, delivery through our CDNs, and basic DAM functionality. These customers utilize and are charged based on their usage of Cloudinary’s storage, bandwidth, and transformation.

Our APIs/SDKs, Media Library Widget, and our Upload Widget might be a good way to integrate to capture these capabilities. You can add common optimization transformations as default (such as ‘f_auto,q_auto’).

DAM

Customers who use Cloudinary’s Digital Asset Management (DAM) solution use Cloudinary’s storage and are able to use Cloudinary’s fully-featured set DAM solution. DAM users do not benefit from Cloudinary’s optimized delivery of assets.

Integrations can make use of our Media Library Widget to embed our DAM capabilities in other platforms and our Upload Widget to allow your customers to upload assets into Cloudinary.

Support multiple accounts, sub-accounts, and users

Cloudinary customers may work with more than one Cloudinary account. For example, agencies managing more than a single account, production/staging accounts, different sub-brands, etc.

A Cloudinary account may contain multiple sub-accounts and multiple users.

The integration can allow the user to switch between different accounts, sub-accounts, and users within the logged-in account, allowing easy “refresh” of the media belonging to the used account/sub-account/user.

back to top

Basic Requirements

This section defines integration requirements that must be followed in order to be listed on Cloudinary’s website.

Installation & update

• Users of the integration must be able to install, update, and uninstall it in the same way as other integrations of the integrated platform.
• Installation instructions and full usage documentation must be clearly presented to the user.
• Known issues and limitations must be clearly presented to the user.
• When the integration is uninstalled, it must remove all Cloudinary functionality added by the integration while not affecting any non-Cloudinary related functionality. The uninstall process must not harm the system, and must end with the system in a fully-functional state.

Login & logout

• The integration must allow the user to use multiple Cloudinary accounts and sub-accounts (clouds). The user must be able to login & logout from multiple accounts and switch between different sub-accounts. Notice that different accounts may have different permission levels.

Contact and support information

• The integration must present clear contact information for users to send questions and report issues. Common ways are in the integration’s UI or a README file.

Technical guidelines

Best practices:

The following aspects are recommendations to better align your integration with other Cloudinary integrations.

• Ensure you have Cloudinary’s latest logos (Brand assets).
• It’s recommended to implement the integration as an open-sourced library hosted on Github.
• If the integration is open-sourced, make sure to follow industry standards, including providing license information, a README file, installation guide, contribution guidelines, and contact information for reporting problems or requesting support.
• Make sure that the code is clean, organized, readable, and follows a consistent coding style.
• The code must be thoroughly tested using automated or manual methods (see Testing guidelines).
• Use the relevant Cloudinary SDK to communicate with Cloudinary’s API.
• Versioning and releases:
  • Make sure the integration release versions comply with the SemVer specification.
  • Present a clear changelog in each new release.

Technical Requirements:

The following aspects must be followed in order for the integration to be certified.

• If the integration uses API key and secret to authenticate with Cloudinary (or any other service), make sure never to expose the API secret in client-side code, your github library, or external communications (for example, video tutorials, training sessions, and screen captures).
• Analytics
  • API calls to Cloudinary must set a user-agent header in the request in the following format:
    Cloudinary<platform>/<plugin ver> (<platform> <ver>) <used SDK>/<ver>
    For example:
    CloudinaryMagento/2.1.0 (Magento 1.9.2.4) CloudinaryPHP/1.6.2
  • When configuring the Media Library widget, a parameter named ‘integration’ must be added as part of the widget’s configuration options.
  • The integration parameter’s data must be in the following format:
    {
type: //the integration identifier e.g. "adobe_connector",
platform: //hosting app name + version e.g. "photoshop 8.6",
version: //integration version e.g. "1.0",
environment: //e.g "prod"/"stag"/"dev"
}

back to top

Below is a list of common and important scenarios Cloudinary will review in your integration.

Storage and delivery:

• Relevant assets are stored and delivered from Cloudinary
• Relevant media types are supported (image/video/raw)
• Various assets types are handled (restricted/private/authenticated)
• Delivery methods (fetch/upload)
• Supported sync options
• Upload presets
• Breakpoints
• Upload/delivery of large files (>1GB)

Transformations:

• Applied as expected
• Multi-level transformations (see Automatic media transformations section)
• Named transformations

Widgets:

• Video player
• Product gallery
• Upload widget
• Media Library Widget

Login/logout:

• Switching accounts and sub-accounts
• Integration disabled/enabled

Integration specific

• Scenarios, features, validations, and limitations specific to the integration product behavior (eg. a maximum of 50 assets presented in the Media Library Widget).
• Scenarios specific to the integration’s implementation (eg. supported rate limits, max queue sizes, etc.)

During the development and testing, if you have any questions or need any consultant, feel free to reach out to our support team or the Cloudinary Integration Team integrations@cloudinary.com.

back to top

Development

While planning your integration, please make sure to take into account best practices, requirements, and testing guidelines in the previous sections.

Once you’re done building and testing your integration, please share your integration by contacting us – integrations@cloudinary.com.

Integration Submission Requirements

Upon submission, you will be required to supply the following:

• Signed technology partner or EMX agreement for legal, privacy, and security purposes.
• Clear installation guidelines.
• Full integration usage documentation.
• Contact person for continued follow-up.
• Video tutorial (preferably) or screen captures of the integration to be posted on our website.
• A description of the different features/options the integration offers and marketing information – a separate form will be sent to collect this information.

When ready, submit your integration here: integrations@cloudinary.com.

Follow up

As part of the process, the Cloudinary Integration Team will check that the integration follows all the guidelines and requirements mentioned.

In some cases, additional information and clarifications might be requested. In such cases, the Cloudinary Integration Team will reach out to the contact person specified during submission.

When complete, the Cloudinary Integration Team will reach out to the primary partner contact to communicate the results of the process.

back to top

Congratulations! You have successfully completed the review process. Please contact the Cloudinary Integration Team at integrations@cloudinary.com for more information on how you can promote the joint solution.

back to top